Skip to content

feat: add thread-safe release api for ending a grasp - #77

Merged
cao-xiao-hao merged 3 commits into
mainfrom
feat/release-api
Oct 29, 2026
Merged

cao-xiao-hao merged 3 commits into
mainfrom
feat/release-api

Conversation

@cao-xiao-hao

Copy link
Copy Markdown
Contributor

Summary

grasp(force_n, hold_s = 0) holds until a fault, so there was no way to end a grip from another thread short of a disconnect. This adds a release API for it, ported from the console's BackOff logic so Studio and the SDK share one implementation.

  • LiteGrip.release(clearance_mm = 10.0, *, abort = false, timeout_s = None) -> ReleaseResult
  • LiteGrip.request_release(clearance_mm = 10.0, *, abort = false) -> bool (queue only, never touches CAN)
  • GraspResult.released, MoveResult.release_requested, ReleaseResult, MotionConfig.release_wait_s

Also removes two internal bench scripts that were tracked in tests/ and should not be published.

Changes

  • Add the cross-thread release state to GripperActions: a request channel the grasp thread drains before every frame, a done event release() waits on, and the hand-over pose the opening is measured from. The lock guards only those fields and never _io_lock.
  • grasp() now ends on a release request: during the force-carrying approach it drops out before hand-over, during the hold it drops the setpoint, and both perform the opening. The hand-over pose and the pending request are recorded in one critical section so a request landing exactly at the hand-over cannot be missed.
  • The opening target is max(current, hand-over pose) + clearance_mm, clamped to the calibrated open stop and run on the existing bounded ramp — the same rule Studio's BackOff used.
  • abort=True drops the torque and sends no opening move; it also overrides a normal release that is still queued (never the reverse). request_release() is the non-blocking twin.
  • With no grasp running, release() opens in the calling thread; a non-finite timeout_s or a negative/non-finite clearance raises CommandError before anything is sent.
  • Tests (TestRelease): cross-thread end of a hold_s = 0 grip, release during the approach, abort form, no-grasp form, second release does not open twice, request_release sends no frames.
  • Docs: method table, result fields, release_wait_s tuning row, and a paragraph in the gripping section.
  • chore: remove internal bench check scripts deletes tests/torque_guard_check.py and tests/trajectory_check.py: hardware bench tools with absolute /home paths that pytest never collects.

Testing

$ env -u LITEGRIP_SDK_PATH python3 -m pytest -q
461 passed, 12 skipped, 57 subtests passed in 10.01s

No hardware was used: the release tests drive the suite's fake CAN plant.

Issues

None.

These are hardware bench tools for this specific setup, not part of the
published SDK: both hardcode absolute /home paths, and one is a one-off
torque guard sweep. The pytest suite does not collect them, so nothing
else changes.
@cao-xiao-hao
cao-xiao-hao merged commit ffa0827 into main Oct 29, 2026
1 check passed
@cao-xiao-hao
cao-xiao-hao deleted the feat/release-api branch October 29, 2026 09:40
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 1.2.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

@github-actions github-actions Bot added the released Shipped in a release label Oct 29, 2026
cao-xiao-hao added a commit to nexform-tech/litegrip-studio that referenced this pull request Oct 29, 2026
The snapshot was taken from the head of upstream's release-API branch
(78b8766), which the squash merge of nexform-tech/litegrip-python#77
replaces with ffa0827 on `main`. The tree is unchanged - verified file by
file against the merged commit - so only the provenance text moves: the
commit hash, the branch caveat, and the per-commit narrative, which now
describes the squash instead of three commits that no longer exist on any
remote branch.
cao-xiao-hao added a commit to nexform-tech/litegrip-studio that referenced this pull request Oct 29, 2026
* build: vendor the litegrip sdk at 78b8766

Moves src/litegrip from cacf392 to 78b8766, ten upstream commits. The one
that matters is the release API: `LiteGrip.release()`, `request_release()`,
`ReleaseResult` and `GraspResult.released`. The rest is packaging, CI and
the deprecation comments of 21e8981; no motion changed and no shipped
calibration file moved, so the tree hash moves but the values do not.

The upstream commit is the head of the release-API branch, not `main`:
upstream PR #77 carries it and this snapshot is taken from it. Re-vendor
from `main` once that PR is merged; the squash merge keeps this tree.

Verbatim copy, as the recipe in VENDORED.md requires - no local edits, and
the tree hash there is recomputed from this tree.

* feat: run grasp and release through the sdk

The real backend now runs a grip as the SDK's force-budgeted grasp() instead
of the console's own approach, and 松开 ends a live grip through
request_release(). That is what makes the hold interruptible: grasp(hold_s=0)
blocks inside its own frame loop, and a release request from another thread
is the only thing that ends it.

- backend: grasp and release run on a registered action thread, exempt from
  the single-owner claim; request_release sends nothing and is callable from
  any thread, so the E-stop can reach a grip that is blocked in its hold.
- worker: one action thread per blocking SDK call, abort routed through
  request_release(abort=True) and bounded by ACTION_ABORT_WAIT_S so a wedged
  CAN send cannot freeze the tick.
- constants: FORCE_MIN_N drops from 6 N to 2 N, the floor the SDK's grasp was
  validated at on this bench. The old floor described the console's own
  approach, which no longer carries the grip; zero stays a mode.
- units and the control page: the floor's wording follows the new meaning.
- tests: the worker's action thread, the abort path, the grip's force floor,
  and grasp/release leaving the backend's forbidden-method list.
- both READMEs: the 2-40 N range and what the lower bound now means.

* docs: point the vendoring note at the merged sdk commit

The snapshot was taken from the head of upstream's release-API branch
(78b8766), which the squash merge of nexform-tech/litegrip-python#77
replaces with ffa0827 on `main`. The tree is unchanged - verified file by
file against the merged commit - so only the provenance text moves: the
commit hash, the branch caveat, and the per-commit narrative, which now
describes the squash instead of three commits that no longer exist on any
remote branch.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

released Shipped in a release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant